using System;
using System.Collections;

namespace Copperline.Escriba
{
	/// <summary>
	/// Interface class for sinking log events
	/// </summary>
	/// <remarks>
	/// Concrete loggers will usually derive from <c>LoggerBase</c>.
	/// <para>Loggers must be composed with a filter and a formatter before
	/// they begin to sink log events.</para>
	/// <para>Loggers should not propagate exceptions. When unrecoverable errors occur,
	/// loggers should take themselves offline by setting <c>Fault</c> to <c>true</c>.
	/// The last error should be storeed in the <c>LastError</c> property.</para></remarks>
	public interface ILogger
	{
		/// <summary>
		/// Setting <c>Enabled</c> to <c>true</c>, permits the logger to sink logging events.
		/// Setting <c>Enabled</c> to <c>false</c> causes the logger to ignore loggine events.
		/// </summary>
		/// <remarks>
		/// This property controls logging.</remarks>
		bool Enabled { get; set; }

		/// <summary>
		/// When <c>Fault</c> is <c>true</c>, the logger is out of service.
		/// </summary>
		/// <remarks>
		/// <c>Fault</c> is set by loggers when serious errors prevent them from
		/// sinking log events. There is no requirement that loggers will be able to 
		/// recover from a fault. Contrast this behavior with <c>Enabled</c>.
		/// <seealso cref="ILogger.Enabled"/></remarks>
		bool Fault { get; set; }

		/// <summary>
		/// Writes a message to the storage medium managed by this logger.
		/// </summary>
		/// <remarks>The logger determines what default priority and other
		/// properties to give the message.</remarks>
		/// <param name="sEntry">the message to be written</param>
		void Write( string sEntry );

		/// <summary>
		/// Writes a complete <c>LogEntry</c> to the storage medium managed by this logger.
		/// </summary>
		/// <param name="logEntry">the <c>LogEntry</c> object holding the message to be
		/// written</param>
		void Write( LogEntry logEntry );

		/// <summary>
		/// Records the last error encountered by the logger.
		/// </summary>
		/// <remarks>Typically, the last error is one that sets <c>Fault</c> to <c>true</c>.
		/// <seealso cref="ILogger.Fault"/></remarks>
		EscribaException LastError { get; set; }

		/// <summary>
		/// Provides a simple means of naming a logger
		/// </summary>
		string Name { get; set; }

		/// <summary>
		/// Sets or gets the formatter associated with this logger
		/// </summary>
		IFormatter Formatter { get; set; }

		/// <summary>
		/// Sets or gets the filter associated with this logger
		/// </summary>
		IFilter Filter { get; set; }
	}
}
